This file details advanced usage options for the Skin Shortcuts script. It is of most use when using Skin Shortcuts to provide the whole the whole main menu system.

Managing Custom Backgrounds
---------------------------

Skin shortcuts can be used to manage backgrounds for your menus.

To do so, you need to define your background options in the overrides.xml file, giving each one a custom ID. You can also set defaults in this file, as well as setting whether the user can browse for a single or multi-image to use as the background. (See "overrides.xml", section 6)

Include a button with the id 310 in your script-skinshortcuts.xml file, which will let the user select from the backgrounds you have defined.

When populating a menu, Skin Shortcuts will then add a 'background' property to each item, containing the custom ID of the background the user has selected, or the image or path they have chosen. You can test against this for visibility, or use a variable to display the image.

	<visible>StringCompare(Container(9000).ListItem.Property(Background),complexBackground)</visible>
	
	<variable name="varBackground">
		<value condition="StringCompare(Container(9000).ListItem.Property(Background),movie)">special://skin/backgrounds/movies.png</value>
		<value condition="StringCompare(Container(9000).ListItem.Property(Background),movieFanart)">$INFO[Window(Home).Property(script.grab.fanart.Movie.FanArt)]</value>
		<value condition="StringCompare(Container(9000).ListItem.Property(Background),weather)">special://skin/weather/$INFO[Window(Weather).Property(Current.FanartCode)]</value>
		<value condition="!IsEmpty(Container(9000).ListItem.Property(Background)">$INFO[Container(9000).ListItem.Property(Background)]</value>
		<value>special://skin/backgrounds/defaultbackground.png</value>
	</variable>

Remembering to replace 9000 with the id of the list containing your menu.

You can also let the user choose to use a playlist for background images for use with, for example, script.grab.fanart, in which case the item will also have the property 'backgroundPlaylist', which will contain the path of the playlist.

It may be advantageous for your submenu items to have the same background property as your main menu items. In which case, include &amp;options=clonebackgrounds in your buildxml command (multiple options can be separated with a pipe - | - symbol.

If you wish to run code based on whether a particular background is active, the script will set the skin property skinshortcuts-background-[backgroundID] for each background currently selected for a menu item. For a background with the ID complexBackground for example, you could use the following in a condition:

	condition="Skin.HasSetting(skinshortcuts-background-complexBackground)"

Custom backgrounds are saved on a skin-by-skin basis.


Managing Widgets
----------------

When using Skin Shortcuts to provide the whole main menu, you may wish to provide a series of widgets - such as PVR information, weather conditions, recently added movies, and so forth - that the user can choose from for each main menu item.

To let the user select from these widgets, include a button with the id 309 in your script-skinshortcuts.xml file.
	
Then use the following in the visibility condition for each widget:

	<visible>StringCompare(Container(9000).ListItem.Property(widget),[WidgetID])</visible>
	
You can define your widgets - along with their WidgetID, an optional widgetType parameter and default labelID's they should appear against - in an overrides.xml file. See "overrides.xml" sections 3 and 4 for more details.

You can also user overrides.xml to let the user select a playlist to use as a widget, which can then be shown by using it as the <content> tag in a list. To check for a playlist widget:
	
	<visible>StringCompare(Container(9000).ListItem.Property(widget),Playlist)</visible>
	
And then set the content of the list as so:

	<content>$INFO[Container(9000).ListItem.Property(widgetPlaylist)]</content>

In all cases, remember to replace 9000 with the ID of the list containing the menu. Widgets are saved on a skin-by-skin basis.

It may be advantageous for your submenu items to have the same background property as your main menu items. In which case, include &amp;options=clonewidgets in your buildxml command (multiple options can be separated with a pipe - | - symbol.

If you wish to run code based on whether a particular widget is attached to a menu item, the script will set the skin property skinshortcuts-widget-[widgetID] for each widget currently selected for a menu item. For a widget with the ID complexWidget for example, you could use the following in a condition:

	condition="Skin.HasSetting(skinshortcuts-widget-complexWidget)"

Widgets are saved on a skin-by-skin basis.


Multiple Sub-Menus
------------------

When using Skin Shortcuts to provide the whole main menu system, you may wish to provide more than one sub menu. For example, you could ape Confluence's favourites - which are displayed below the main and sub-menu's - with an additional sub menu.

To cause the script to build the additional submenus, include levels=[number of additional submenus] in the build command. You can build up to an additional 5 menus.

	RunScript(script.skinshortcuts,type=buildxml&amp;mainmenuID=9000&amp;levels=1)

Then include the additional submenu in the list where you want the items to appear.

	<include>skinshortcuts-submenu-1</include>
	
Where the number at the end is the number of additional submenu you want displayed.

Within the management dialog, include buttons in the range of 405 - 410 to allow the user to manage the items within the additional submenu. See "Management Dialog.txt" for details.

Alternative Listing Methods
---------------------------

As a test of alternative methods of listing shortcuts, skin shortcuts can now generate a single list containing all main and sub-menu items (includes method only) by calling buildxml with the optional paramater mode set to buildsingle.

This is intended only to demonstrate the possibility of including build methods that would be specific to a skin.


Just Select Shortcuts
---------------------

If you don't want to take advantage of the scripts menu management functions, you can still use the script to display available shortcuts to the user. The shortcut the user selects is then passed back to the skin for you to manage.

When using this method, you specify which skin strings you want the script to set - you can then access these as normal via Skin.String.

To use the script in this way, put the following in an onclick:

RunScript(script.skinshortcuts,type=shortcuts&amp;custom=[True/False]&amp;showNone=[True/False]&amp;skinLabel=[skinLabel]&amp;skinAction=[skinAction]&amp;skinType=[skinType]&amp;skinThumbnail=[skinThumbnail])

custom=[True/False] - Whether you wish to allow the user to type their own custom command. If ommitted this will default to False. [OPTIONAL]
showNone=[True/False] - Whether you wish to show a 'None' option to reset skin labels. If ommitted this will default to False. [OPTIONAL]
[skinLabel] - The skin string the script will write the label of the selected shortcut to. [OPTIONAL]
[skinAction] - the skin string the script will write the action of the selected shortcut to. [OPTIONAL]
[skinType] - The skin string the script will write the type of the selected shortcut to. [OPTIONAL]
[skinThumbnail] - The skin string the script will write the thumbnail of the selected shortcut to. [OPTIONAL]


Overrides.xml
-------------

Your skin can include an optional file called 'overrides.xml' in a sub-directory of your skin called 'shortcuts'. This file allows you to provide various defaults for Skin Shortcuts, as well as overriding various things including actions and icons, allowing you to create a customised experience for your skin.


1. Overriding an action

You may wish to override an action in order to provide additional functionality. For example, you could override the default action for Movies (to go to the Movie Title view) to run Cinema Experience instead.

Note, any override will replace the original menu item with one which is only visible when any conditions are met. This means you will also need an override for when the conditions are not met.

<override action="[command]" group="[GroupName]" version="[XBMC Major Version]">
	<condition>[Boolean condition]</condition>
	<action>[XBMC function]</action>
<override>
	
[command] - Replace with the action you are overriding
[GroupName] - [Optional] The group that the override applies to, for example "movies". If omitted, the property will be apply to all items which match the action.
[XBMC Major Version] - [Optional] The major XBMC version on which this override will occur, for example "13" for XBMC Gotham
[Boolean condition] - [Optional] Replace with a string that must evaluate to True for the custom action to be run
[XBMC function] - Replace with the action that should be run instead. You may include multiple <action> tags. Omit to run the original command.

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<override action="ActivateWindow(Videos,MovieTitles,return)">
		<condition>!Skin.HasSetting(CinemaExperience) | !System.HasAddon(script.cinema.experience)</condition>
	</override>
	<override action="ActivateWindow(Videos,MovieTitles,return)">
		<condition>Skin.HasSetting(CinemaExperience) + System.HasAddon(script.cinema.experience)</condition>
		<action>RunScript(script.cinema.experience,movietitles)</action>
	</override>
</overrides>

Please be aware that in the latest revisions of the script, library links - ActivateWindow(Videos,MovieTitles) - have been replaced by video nodes - ActivateWindow(Videos,videodb://movies/titles/). You should ensure any overrides work with both types of link.

IMPORTANT: User choice MUST be respected when overriding actions. That is to say, unless the user specifically gives permission for a shortcut they have chosen to do something else, it should be left alone. If you are overriding the action, it is expected that in most cases you will use a visibility condition - possibly linked to a skin settings - to ensure the user has consented.

Users can also provide an overrides.xml file to override actions in special://profile/


2. Overriding icons

The script tries to provide reasonable default images for all shortcuts, with a fallback on "DefaultShortcut.png", however you may wish to override images to specific ones provided by your skin.

This can be done by providing an optional file called 'overrides.xml' in a sub-directory of your skin called 'shortcuts'. It provides two ways to override images - either overriding the image for a specific labelID, or overriding all instances of a particular image - as follows:

<icon labelID="[labelID]" group="[GroupName]" grouping="[Grouping]">[New image]</icon>
<icon image="[Old image]" group="[GroupName]" grouping="[Grouping]">[New image]</icon>

[labelID] - The labelID whose icon you want to override
[Old image] - The image you are overriding
[GroupName] - [Optional] The group (submenu) that the labelID or image must be in, for example "movies". If omitted, the property will be apply to all items which match the labelID or image.
[Grouping] - [Optional] The grouping (available shortcuts) that the labelID or image must be in. If omitted, the property will be applied to all items which match the label ID or image
[New image] - The replacement image

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<icon labelID="movies">MyMovieImage.png</icon>
	<icon image="DefaultShortcut.png">MyShortcutImage.png</icon>
</overrides>

Note, if you override icons in the available shortcut groupings the menu items will have these overrides as their icons, so different overrides for menu groups may not work as expected.
Note, any thumbnail image provided by the shortcut or set by the user has set will take precedence over skin-provided overrides.

A full list of labelID's and default icon images can be found in the Resources folder. A full list of groupings can be found below, in section 5 (Skin Recommended Shortcuts).

By default, when an available shortcut has a thumbnail (add-ons, favourites, etc) these cannot be overriden. It is possible to return these as the icon (which can be overriden) by including the following in your overrides.xml:

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<useDefaultThumbAsIcon>True</useDefaultThumbAsIcon>
</overrides>

IMPORTANT: In previous versions this element was called <thumbnail> - please update any old elements.


3. Custom background images

If you are using Skin Shortcuts to manage background images, provide a list of backgrounds and defaults for labelID's in the overrides.xml.

<background label="[Label]" condition="[Condition]">[backgroundID]</background>
<backgrounddefault labelID="[LabelID]" group="[GroupName]">[backgroundID]</backgrounddefault>

[Label] - The display name of the background (can be a localised string)
[Condition] - [Optional] Boolean condition that must be true for the background to show in the management dialogs Background Select (evaluated when management dialog is loaded)
[GroupName] - [Optional] The group that the labelID must be in, for example "movies". If omitted, the default will apply to items in the main menu.
[backgroundID] - A string you use to identify the background
[labelID] - The labelID you are providing a default for. (Replace with defaultID="[defaultID]" to set default based on this property instead)

If you want to let the user browse for either a single or multi-image background, also include:

<backgroundBrowse default="protocol://path/to/folder">True</backgroundBrowse>

where default is an optional path to the folder that will be displayed by default in the select dialog.

You can also let the user choose a playlist to use as a background. In that case, set the label to a localised string containing the string "::PLAYLIST::". Skin Shortcuts will create multiple copies of this entry, with ::PLAYLIST:: replaced by the name of each of the users defined playlists. List items will then have the additional property "backgroundPlaylist", containing the path of the playlist.

Note, you can use the script to manage backgrounds for main menu and sub-menu items, but you can only set defaults for main menu items.
	
<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<background label="Weather">weather</background>
	<background label="30222">movieFanart</background>
	<background label="Images from ::PLAYLIST::>playlistBackground</background>
	<backgrounddefault labelID="movies">movieFanart</backgrounddefault>
	<backgrounddefault labelID="weather">weather</backgrounddefault>
	<backgroundBrowse>True</backgroundBrowse>
</overrides>

You can then choose which background to display based on the 'background' property of the selected listitem.


4. Widgets

If you are using Skin Shortcuts to manage widgets, provide a list of the widgets your skin supports and defaults for labelID's in the overrides.xml.

<widget label="[label]" condition="[Condition]" type="[type]">[WidgetID]</widget>
<widgetdefault labelID="[labelID]" group="[GroupName]">[widgetID]</widgetdefault>

[label] - The display name of the widget, to be shown when choosing widgets (can be a localised string)
[Condition] - [Optional] Boolean condition that must be true for the background to show in the management dialogs Background Select (evaluated when management dialog is loaded)[type] - [Optional] A string you use to identy the type of widget (returned as property widgetType)
[GroupName] - [Optional] The group that the labelID must be in, for example "movies". If omitted, the property will apply to items in the main menu.
[widgetID] - A string you use to identify this widget
[labelID] - The labelID you are setting the default for. (Replace with defaultID="[defaultID]" to set default based on this property instead)

If you want the user to be able to select a playlist as a widget, also include:

<widgetPlaylists type="[type]">True</widgetPlaylists>

So, for example:

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<widget label="PVR Status">PVR</widget>
	<widget label="30222">RecentMovies</widget>
	<widgetdefault labelID="movies">RecentMovies</widgetdefault>
	<widgetdefault labelID="livetv">PVR</widgetdefault>
	<widgetPlaylists>True</widgetPlaylists>
</overrides>

You can then choose which widget to display based on the 'widget' property of the selected listitem.

You can optionally use choose to set the shortcut name to the widget name when selecting a widget. To do so, set the window property "useWidgetNameAsLabel" to "true". This property will be reset after the widget is set.


5. Skin-Recommended Shortcuts

If there are particular shortcuts to skin-specific features you would like to give the user the option of choosing from, you can specify these in the overrides.xml.

<shortcut label="[label]" type="[type]" grouping="[grouping]" thumbnail="[thumbnail]" icon="[icon]" condition="[Boolean condition]">[action]</shortcut>

[label] - The display name of the shortcut (can be a localised string)
[type] - Indicated the type of shortcut to the user, e.g. "Movie" if this leads to an area of the movie library (can be a localised string)
[grouping] - [Optional] The shortcut group this should appear within - see below
[thumbnail] - [Optional] The thumbnail associated with the shortcut
[icon] - [Optional] The icon associated with the shortcut
[Boolean condition] - [Optional] Replace with a string that must evaluate to True for the shortcut to appear
[action] - The action associated with this shortcut

Note - If the action is overridden (see section 1), this will take precedence over any boolean conditions specified here.

Shortcut groupings within the management dialog are made up of several smaller groupings, to which you can add your own shortcuts with the grouping parameter. Available groups are:
 - common
 - commands
 
 - video
 - movie
 - tvshow
 - musicvideo
 - customvideonode
 - videosources
 
 - music
 - musicsources
 
 - picturesources
 
 - pvr
 - radio 			(Helix)
 - pvr-tv
 - pvr-radio
 
 - playlist-video
 - playlist-audio
 
 - addon-program
 - addon-video
 - addon-audio
 - addon-image
 
 - favourite
 
If you do not specify a grouping, it will be added to the end of the common group.


6. Skin-required shortcuts

When using the script to provide the whole menu, you can specify shortcuts that are required for the skin to appear in the main menu. If there is no main menu item with the specified action, an additional shortcut will be created. Users will be unable to delete these shortcuts whilst using your skin.

<requiredshortcut label="[label]" thumbnail="[thumbnail]" icon="[icon]">[action]</requiredshortcut>

[label] - The display name of the shortcut (can be a localised string)
[thumbnail] - [Optional] The thumbnail associated with the shortcut
[icon] - [Optional] The icon associated with the shortcut
[action] - The action associated with this shortcut

Note, the type will be set to the id of your skin (skin.name) to indicate that it is specific to the skin.


7. Check for shortcut in menu system

You can ask the script to check whether a shortcut with a given action is present within the menus it builds. It will then set a skin boolean based on whether it appears or not.

<checkforshortcut property="[propertyName]">[action]</checkforshortcut>

[propertyName] - The name of the skin boolean that will be set or cleared, dependant on existance of action
[action] - The action to check for


8. Override label of available shortcuts

If you want to provide a different label for the list of available shortcuts in the management dialog, you can specify this here.

	<availableshortcutlabel action="[command]" type="[type]">[New Label]</availableshortcutlabel>
	
[command] - The command of the available shortcut whose label you are overriding
[New Label] - The label you want to replace the default label with (can be a localised string)
[type] - [Optional] Indicated the type of shortcut to the user, e.g. "Movie" if this leads to an area of the movie library (can be a localised string)

So, for example,

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<availableshortcutlabel action="ActivateWindow(Videos,RecentlyAddedMovies,return)">New Movies</availableshortcutlabel>
	<availableshortcutlabel action="ActivateWindow(Videos,RecentlyAddedMovies,return)">30222</availableshortcutlabel>
</overrides>

Please note - you can ONLY override shortcuts in the following groups: Common, XBMC Commands, Video Library, Music Library
You can NOT override the labels for user's own defined custom video nodes.


9. Custom shortcut properties

If you are using Skin Shortcuts to set custom properties for shortcuts, you can set defaults for these items:

	<propertydefault labelID="[LabelID]" group="[GroupName]" property="[Property]">[Property Value]</propertydefault>
	
[labelID] - The labelID you are providing a default for.
[GroupName] - [Optional] The group that the labelID must be in, for example "movies". If omitted, the property will be apply to items in the main menu.
[Property] - The string used to identify the property
[Property Value] - The default value of the property

If you are using Skin Shortcuts to set these properties, then you must also set the available options:

	<property property="[Property]">[Property Value]</property>

[Property] - The string used to identify the property
[Property Value] - The default value of the property

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<propertydefault labelID="movies" property="description">Browse your movies</propertydefault>
	<property property="description">Browse you movies</property>
	<property property="description">31234</property>	
</overrides>


10. Overriding settings labels

When using Skin Shortcuts to provide the whole main menu, it can provide a list of controls for your skinsettings.xml to launch the management dialog. You can override the default labels for these controls.

<settingslabel type="[type]" level="[level]">[string]</settingslabel>
	
[type] - Either "main" (Main Menu), "submenu" (sub menu item) or "reset" (Reset all shortcuts)
[string] - The label that should be displayed. Can be a localised string. For "submenu", you can include ::MENUNAME:: where you want the name of the menu to appear.

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<settingslabel type="main">Choose what to display on the main menu</settingslabel>
	<settingslabel type="submenu">Pick submenu items for ::MENUNAME::</settingslabel>
	<settingslabel type="reset">Reset all shortcuts back to default</settingslabel>
</overrides>


11. Warn and confirm user wants to delete shortcut

You can use the overrides.xml to warn the user before they delete any particular shortcut and to give them the chance to cancel, for example to settings.

<warn heading="[heading]" message="[message]">[Action]</warn>

[heading] - The heading of the Yes/No dialog that will be shown to the user (can be a localised string)
[message] - The message in the Yes/No dialog that will be shown to the user (can be a localised string)
[action] - The action of the existing shortcut that will trigger this message when the user tries to delete/replace it, or edit its action


12. Force Settings Link

When using Skin Shortcuts to provide the whole main menu, it is possible for the user to delete the link to settings. This would leave them in a position where they are unable to further edit the menu to put it back.

It is recommended that you provide an alternative access to settings somewhere in your skin, such as the power menu. However, if you do not, then it is possible to force the script to add a Settings option to the end of the main menu, if there is no other link to settings in the menu structure.

<?xml version="1.0" encoding="UTF-8"?>
<overrides>
	<forcesettings>True</forcesettings>
</overrides>

Please note, this will cause the script to create a shortcut with the action ActivateWindow(Settings) if none exists. It doesn't look for any other settings area links. It also doesn't take into account any overrides or visibility conditions that may be attached to a shortcut.


13. Provide available thumbnails

When using button 311 in the management dialog, you can provide a list of thumbnails the user can choose from for their shortcut.

<thumbnail label="[label]">[path]</thumbnail>

[label] - The name displayed to the user in the select dialog
[path] - The path to the image. No need to include full path if the thumbnail is included with your skin.


Localisation
------------

If you are providing default shortcuts and want to localize your label, you can do it using the format

  [id]
  
Where [id] is any string id provided by XBMC or your skin.

You can use a string id by your skin, but be aware that it will only stay localised if the user switches languages whilst the user is using your skin.

In your overrides.xml file, you can just use the string id provided by XBMC or your skin directly. As the overrides.xml is specific to your skin, it is safe to use strings provided by your skin in it.

In order to make things easier for skinners using this script to provide the main menu, listitems returned by the script have the property labelID. This is a non-localized string that can be tested against (for visibility, for example).

For common main menu items, it will contain one of the following strings
	videos
	movies
	tvshows
	livetv
	radio 			(Helix)
	music
	musicvideos
	pictures
	weather
	programs
	dvd
	settings
	
For other localized strings, it will contain the id of the string. For non-localized strings, it will contain the string in lowercase and without any spaces.

A full list of labelID's can be found in the Resources folder.

If you are using either "::MENUNAME::" or "::PLAYLIST::" (or similar) in your skins localised strings, it's recommended to leave a note for translators that these should NOT be translated, otherwise users in different languages may not have all options.
